// API: 成绩管理相关接口
import { apiClient } from '@/utils/require'

/**
 * 成绩类型定义
 */
export interface GradeDetail {
  id: number
  student?: any
  student_id?: number | string
  student_name?: string
  major_name?: string
  class_name?: string
  course_no?: number
  course_name: string
  grade: string
  time?: number
  created_at: string
  updated_at: string
}

export interface PaginatedResponse<T> {
  count: number
  next: string | null
  previous: string | null
  results: T[]
}

/**
 * 成绩管理API
 * 
 * API说明：
 * - 基础路径：/api/grades/
 * - 认证方式：Token认证
 * - 权限控制：
 *   - 查看成绩：学生可查看自己的，教师可查看所有
 *   - 录入/修改/删除：仅教师及以上权限
 * - 用途：学生课程成绩录入与查询，用于计算综测分
 */
export const gradeAPI = {
  /**
   * 获取成绩列表
   * 
   * 接口：GET /api/grades/
   * 权限：已认证用户（学生仅看自己，教师看所有）
   * 
   * @param params 查询参数
   * @param params.page 页码
   * @param params.page_size 每页数量
   * @param params.student_id 按学号筛选
   * @param params.student_name 按姓名筛选
   * @param params.major 按专业筛选
   * @param params.class_name 按班级筛选
   * @param params.time 按学年筛选
   * @param params.course_name 按课程名搜索
   * @param params.min_grade 最低成绩
   * @param params.max_grade 最高成绩
   * @param params.ordering 排序方式
   * 
   * @returns 成绩列表
   */
  getGradeList: (params?: {
    page?: number
    page_size?: number
    student_id?: string
    student_name?: string
    major?: string
    class_name?: string
    time?: number
    course_name?: string
    min_grade?: number
    max_grade?: number
    ordering?: string
  }) => {
    return apiClient.get<PaginatedResponse<GradeDetail>>('/grades/', { params })
  },

  /**
   * 获取成绩详情
   * 
   * 接口：GET /api/grades/{id}/
   * 权限：已认证用户
   * 
   * @param id 成绩ID
   * @returns 成绩详细信息（包含学生信息、课程信息）
   */
  getGradeDetail: (id: number) => {
    return apiClient.get<GradeDetail>(`/grades/${id}/`)
  },

  /**
   * 录入成绩
   * 
   * 接口：POST /api/grades/
   * 权限：仅教师及以上
   * 
   * @param data 成绩数据
   * @param data.student_id 学生ID（必填）
   * @param data.course_no 课程号（选填）
   * @param data.course_name 课程名（必填）
   * @param data.grade 成绩（必填，可以是数字或等级）
   * @param data.time 学年（必填）
   * 
   * @returns 创建成功的成绩记录
   * 
   * @example
   * gradeAPI.createGrade({
   *   student_id: 1,
   *   course_name: '高等数学',
   *   grade: '85',
   *   time: 2024
   * })
   */
  createGrade: (data: Partial<GradeDetail>) => {
    return apiClient.post('/grades/', data)
  },

  /**
   * 更新成绩
   * 
   * 接口：PUT /api/grades/{id}/
   * 权限：仅教师及以上
   * 
   * @param id 成绩ID
   * @param data 更新的成绩数据
   * @returns 更新后的成绩信息
   */
  updateGrade: (id: number, data: Partial<GradeDetail>) => {
    return apiClient.put(`/grades/${id}/`, data)
  },

  /**
   * 删除成绩
   * 
   * 接口：DELETE /api/grades/{id}/
   * 权限：仅教师及以上
   * 
   * @param id 成绩ID
   * @returns 204 No Content
   */
  deleteGrade: (id: number) => {
    return apiClient.delete(`/grades/${id}/`)
  },

  /**
   * 成绩统计
   * 
   * 接口：GET /api/grades/statistics/
   * 权限：已认证用户
   * 
   * @param params 统计参数
   * @param params.class_name 按班级统计
   * @param params.time 按学年统计
   * 
   * @returns 成绩统计数据（平均分、及格率等）
   */
  getStatistics: (params?: { class_name?: string; time?: number }) => {
    return apiClient.get('/grades/statistics/', { params })
  },

  /**
   * 学生成绩矩阵：横向展示
   * 
   * 接口：GET /api/grades/student_matrix/
   * 权限：已认证用户
   * 
   * @param params 查询参数
   * @param params.student_id 按学号筛选
   * @param params.student_name 按姓名筛选
   * @param params.major 按专业筛选
   * @param params.grade_year 按年级筛选
   * @param params.class_name 按班级筛选
   * @param params.time 按学年筛选
   * @param params.page 页码
   * @param params.page_size 每页数量
   * 
   * @returns 横向展示的学生成绩数据
   */
  getStudentMatrix: (params?: {
    student_id?: string
    student_name?: string
    major?: string
    grade_year?: string
    class_name?: string
    time?: number
    page?: number
    page_size?: number
  }) => {
    return apiClient.get('/grades/student_matrix/', { params })
  },

  /**
   * 成绩视图：按学生分组展示
   * 
   * 接口：GET /api/grades/student_view/
   * 权限：已认证用户
   * 
   * @param params 查询参数
   * @param params.student_id 按学号筛选
   * @param params.student_name 按姓名筛选
   * @param params.major 按专业筛选
   * @param params.class_name 按班级筛选
   * @param params.time 按学年筛选
   * @param params.page 页码
   * @param params.page_size 每页数量
   * 
   * @returns 按学生分组的成绩数据，包含统计信息
   */
  getStudentView: (params?: {
    student_id?: string
    student_name?: string
    major?: string
    class_name?: string
    time?: number
    page?: number
    page_size?: number
  }) => {
    return apiClient.get('/grades/student_view/', { params })
  },

  /**
   * 批量导入成绩
   * 
   * 接口：POST /api/grades/batch_import/
   * 权限：仅教师及以上
   * 
   * @param file Excel文件
   * @param time 学年
   * 
   * @returns 导入结果统计
   * 
   * @example
   * const formData = new FormData()
   * formData.append('file', file)
   * formData.append('time', '2024')
   * gradeAPI.batchImport(formData)
   */
  batchImport: (formData: FormData) => {
    return apiClient.post('/grades/batch_import/', formData, {
      headers: {
        'Content-Type': 'multipart/form-data'
      }
    })
  }
}

export default gradeAPI
